﻿// -----------------------------------------------------------------------
// <copyright file="IStreamReader.cs" company="Company">
// Company 2011
// </copyright>
// -----------------------------------------------------------------------

using System.Runtime.InteropServices;
using System.Security;
using System.Text;

namespace Company.IO.Interfaces
{
    /// <summary>
    /// Implements a TextReader that reads characters from a byte stream in a particular encoding.
    /// </summary>
    [Guid("e6082920-f3ab-4b5a-96a4-1c062758792c")]
    public interface IStreamReader
    {
        /// <summary>
        /// Gets the current character encoding that the current StreamReader object is using.
        /// </summary>
        Encoding CurrentEncoding { get; }

        /// <summary>
        /// Returns the underlying stream.
        /// </summary>
        IStream BaseStream { get; }

        /// <summary>
        /// Gets a value that indicates whether the current stream position is at the end of the stream.
        /// </summary>
        bool EndOfStream { [SecuritySafeCritical]
        get; }

        /// <summary>
        /// Closes the StreamReader object and the underlying stream, and releases any system resources associated with the reader. (Overrides TextReader.Close().)
        /// </summary>
        void Close();

        /// <summary>
        /// Clears the internal buffer.
        /// </summary>
        void DiscardBufferedData();

        /// <summary>
        /// Returns the next available character but does not consume it. (Overrides TextReader.Peek().)
        /// </summary>
        /// <returns>
        /// An integer representing the next character to be read, or -1 
        /// if there are no characters to be read or if the stream does not support seeking.
        /// </returns>
        [SecuritySafeCritical]
        int Peek();

        /// <summary>
        /// Reads the next character from the input stream and advances the character position by one character. (Overrides TextReader.Read().)
        /// </summary>
        /// <returns>The next character from the input stream represented as an Int32 object, or -1 if no more characters are available.</returns>
        [SecuritySafeCritical]
        int Read();

        /// <summary>
        /// Reads a specified maximum of characters from the current stream into a buffer, beginning at the specified index.
        /// </summary>
        /// <param name="buffer">
        /// When this method returns, contains the specified character array with the values between 
        /// index and (index + count - 1) replaced by the characters read from the current source.
        /// </param>
        /// <param name="index">The index of buffer at which to begin writing.</param>
        /// <param name="count">The maximum number of characters to read.</param>
        /// <returns>
        /// The number of characters that have been read, or 0 if at the end of the stream and no data was read. 
        /// The number will be less than or equal to the count parameter, 
        /// depending on whether the data is available within the stream.
        /// </returns>
        [SecuritySafeCritical]
        int Read([In, Out] char[] buffer, int index, int count);

        /// <summary>
        /// Reads the stream from the current position to the end of the stream.
        /// </summary>
        /// <returns>The rest of the stream as a string, from the current position to the end. 
        /// If the current position is at the end of the stream, returns an empty string ("").</returns>
        [SecuritySafeCritical]
        string ReadToEnd();

        /// <summary>
        /// Reads a line of characters from the current stream and returns the data as a string.
        /// </summary>
        /// <returns>The next line from the input stream, or a null reference (Nothing in Visual Basic) if the end of the input stream is reached.</returns>
        [SecuritySafeCritical]
        string ReadLine();
    }
}